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Preface 


The DASL USER's GUIDE, Vol. III, is another reference in 
the DASL library. Vol. III describes the NOSL I/O package. 


This work is a DATEC production. NOSL I/O was written on 
a DATAPOINT processor using an experimental writing 

tool. Then, the masters for printing were produced on a 
DATAPOINT 9660 Laser Printer. 


Please forward your comments on this document to: 
DATEC Publications 
DATAPOINT Corporation 
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INTRODUCTION 
OVERVIEW 


About this manual 


This manual describes the NOSL I/O package. It contains 
general information about the NOSL I/O package for 
programmers who are unfamiliar with NOSL, and contains 
instructions for including NOSL, calling sequences for the 
NOSL functions, and descriptions of the internal memory 
manager and error handler. 


Intended audience 


This manual is intended for programmers writing software 
in DASL on the RMS operating system. 


It contains code segments of DASL programs that reference 
the RMS operating system. 
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OVERVIEW 


How this manual is organized 


This manual is divided into seven chapters. 


pot fan introduction to the NOSL I/O package. 


1 
m2: procedures for including the NOSL I/O 


package into your DASL program. 


Poa fa description of the NOSL functions. 


A description of the different types of nosls 
and instructions for opening a nosl. 


A description of the numeric scanners that are 
part of the NOSL I/O package. 


A description of the NOSL internal memory 
manager and its relationship to virtual files 
and overlays. 


A description of the NOSL error handler and 
instructions for customizing error handling. 
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Introduction 


As a DASL programmer, you are probably aware that DASL 
has no internal I/O facility. In order to generate I/O, you 
must use one of the RMS I/O packages, or create your own 
I/O package. 


NOSL has been written as an easy to use, but powerful I/O 
package for the DASL programming language. 


NOSL sets up tables and buffers 


Performing I/O under RMS often requires you to provide 
memory for tables and buffers. The fields in these tables 
must in turn be initialized. 


NOSL allocates memory for these tables and buffers, and 
initializes the tables with common default values, while 
giving you the flexibility to override the default values. 


NOSL has common interfaces called nosls 


NOSL provides a common interface to access a variety of 
devices. 


Individual modules, called nosls, interface to the different 
devices. For every device supported by the NOSL I/O 
package, there is a corresponding nos]. 
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NOSLS AND STREAMS 


Introduction 


The term "device" is often used to refer to printers, 
keyboards, and screens. In the previous section we 
learned that there is a corresponding nos! for every device 
supported by the NOSL I/O package. 


In this section, we will find out that a nos! can also 
interface to another nosi. Because "device" does not 
accurately describe this interface, the term "stream" will 
be used to describe all NOSL interfaces instead. 


Definition of a stream 


A stream is anything whose contents can be treated as a 
sequence of bytes. Some examples of streams are 


e a text file, 

e a printer, 

e a keyboard, and 
e anosl. 


n$Stream type 


NOSL provides a type, n$Stream, to describe a stream. The 
NOSL open function returns a variable of this type, while 

the other NOSL I/O functions require a variable of this type 
as an input parameter. 


Example: 


ia nSStream; 
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NOSLS AND STREAMS 


Streams are sequences of bytes 
A stream is treated as a sequence of bytes. 


The length of a stream is always measured as the number 
of bytes from the beginning to the ending of a stream. 


Stream pointers 


NOSL maintains a pointer to the current byte position of 
each stream. This stream pointer advances whenever 
reading or writing is performed on the stream, and can be 
examined and changed on certain streams. 


Note: The first byte in a stream is at position zero. The 
stream pointer is generally set to zero when a Stream is 
opened. 


Nosls translate data to and from streams 


Nosls are used to translate data to and from a stream. 
Since data is formatted differently within each stream, the 
nosis will 


e remove device dependencies from input streams, and 
e add device dependencies into output streams. 


Example: The Decomp nosl translates compressed text from 


an input stream into uncompressed text. The CmpOut nosl 
translates uncompressed text into compressed text. 
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NOSLS AND STREAMS 


Nosls may be layered 


Nosls may be layered on top of one another if more than 
one translation of a stream is needed. 


Example: In order to read a standard RMS text file, a text 
decompression nos! must be layered on top of a binary disk 
nosl which inputs the compressed RMS text file. 


Compressed 
RMS Text File 


Binary Disk 
Nosl 


Text 
Decompression 
Nosl 
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Chapter 2. 


INCLUDING NOSL 
OVERVIEW 


Introduction 


This chapter contains the procedures that are needed to 
include the NOSL I/O package into your DASL program. 


Overview of the procedure 
The procedures for including the NOSL I/O package are 


outlined in the following table. A description of each 
procedure in this table is included in this chapter. 


I Include the NOSL definition file into your DASL Jf 
program. 

2 Include the NOSL relocatable library in your LINK 
directives. 
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INCLUDE NOSL DEFINITION FILE 


Introduction 


The NOSL definition file must be included in the INCLUDE 
portion of your DASL program. 


ak Include the NOSL definition file into your DASL 
|}program. 


What is the NOSL definition file 
The NOSL definition file is a text file that contains 
definitions and external references that are needed to 


reference the NOSL I/O package. 


Its name is "N$/DEFS". 


Example 


INCLUDE( DS INC ) 
INCLUDE(DSRMS ) 
INCLUDE(NS/DEFS ) 


: Crest of the program) 
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INCLUDE NOSL RELOCATABLE LIBRARY 


Introduction 


The NOSL relocatable library must be included by the 
LIBRARY directive in LINK. 


Include the NOSL relocatable library in your LINK[ 


directives. 


Selecting the correct NOSL library 


There are a couple of copies of the NOSL relocatable 
library that support two of the DATAPOINT instruction 
sets. Use this table to select the proper NOSL library for 
your instruction set. 


If you are writing for the... 
5500 instruction set NS /REL5 
6600 instruction set NS /REL 


Also include the CUFs library 
NOSL uses several of the common user functions, CUFs. 


The appropriate CUFs relocatable library must be included 
after the NOSL relocatable library in your LINK directives. 
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INCLUDE NOSL RELOCATABLE LIBRARY 


Example 


If you had selected N$/REL, your LINK directives might 
look like this: 


SEGMENT MYPROG 
INCLUDE DASLASM 


INCLUDE DSLIB.DSSTART 
LIBRARY NS 

LIBRARY SCUFS 
LIBRARY DSLIB 
LIBRARY RMSUFRS 


o¢ 
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Chapter 3. 
THE NOSL FUNCTIONS 
OVERVIEW 


Introduction 


This chapter contains descriptions of the eleven NOSL 
functions that may be called by your DASL program to 


access the nosls. 


Description 


The NOSL functions are a set of functions that give you the 
ability to open, close, and manipulate a stream. 


Note: A description of the individual nosls are found in the 
next chapter. 


Parameterization of the NOSL functions 


Parameters in some of the NOSL functions are optional. 


Optional parameters are enclosed in square brackets for 
identification in the function diagrams. They may be 
ignored by omitting them completely, or by replacing them 
with a comma if a later parameter is to be specified. 
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OVERVIEW 


NUMBER type 
NOSL defines a type, NUMBER, which represents the 
addressable memory area of a machine. This type is used 


in the NOSL read and write functions. 


On machines with 16 bit pointers, NUMBER is defined as 


follows: 


Type Definition 


TYPDEF NUMBER UNSIGNED; |Addressable memory area of a 
imachine. 


Note: On machines with 32 bit pointers, NUMBER is defined 
as LONG. 
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OVERVIEW 


Selecting a NOSL function 


Use the following table to determine which NOSL function 
to use. 


= 
= 


close a stream = asclose 
output formatted data to a stream 3-15 


348 
349 


3-10 
=i 
+13 
-14 


3 
3 
3 
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n$Sopen 


n$open function 


n$open Opens a stream. 
Note: The n$open function is the only function that is 
parameterized differently for different nosls. See the next 


chapter for the different parameterizations. 


All stream types support n$open. 


nSopen ( 
st StreamType, 


Type of stream 
to open. 


Address of a 
function to call 
if an error 
occurs. 
Note: See Error 
Handling. 


eF a nSErrorFunc |, 


Address of data 
to pass into the 
error function. 
Note: See Error 
Handling. 


eD a nSErrorData 1], 


Other parameters 
depending on the 
type of stream 

opened. 


other parameters |] 


Opened stream. 
NIL if unable 
to open the 

stream. 


) nSStream; 


See the next chapter for examples. 
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n$read 


n$read function 
n$read reads bytes from an input stream. 
Some nosls do not support n$read. 


nSread ( 
s nSStream, 


Stream to read from. 


Address of the first 
byte to store the 
data read from the 
stream. 


p a BYTE, 


Number of bytes to 
read. 


len NUMBER 


Number of bytes 
actually read. 
Note: 0 if 
end-of-file. 


) NUMBER ; 


Example: 


in nSStream; 


function () := 
VAR String [81] CHAR; 
n BYTE; 


n := nSread(in, &string!0], SIZEOF string); 
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nwrite 
i sts 


n$write function 
n$write writes bytes to an output stream. 


Note: If there is already data where the stream is 
positioned, it will be overwritten. 


Some nosls do not support n$write. 


nSwrite ( 
s nSStream, 


Stream to write to. 


Address of the first byte to 
write to the stream. 


|Number of bytes to write. 


p a BYTE, 


len NUMBER 
3 


Example: 


out nSStream; 


function () := 
VAR STATIC s [] CHAR := ‘Hello'; 


{ 
n$write(out, &s[0], SIZEOF s); 
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n$tell 


n$tell function 


n$tell returns the current position of the stream in bytes. 
Some nosls do not support n$tell. 


nStell (¢ 
s nSStream 


Stream to determine 
the current byte 
position. 


Current byte 
position of the 
stream. 


Example: 


file nS$Stream; 


function () := 
VAR pos LONG; 


{ 
pos := nSteli(file); 


Chapter is Tae: NOSE. FUNC ELONS 6 eae | 


n$seek 


n$seek function 


Some nosls do not support n$seek. 


nSseek ( 
s nSStrean, 


Stream to change the 
byte position. 


n$seek positions the stream to a certain byte position. 
Byte location to 


pos LONG 


) LONG; 


Example: 


file nSStream; 


function () := 
VAR pos LONG; 


{ 
pos := nSseek(file, 0); 
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n$size 


n$size function 
n$size returns the size of a stream in bytes. 


Some nosls do not support n$size. 


nSsize ( 
s n$Stream Stream to determine 
the size. 


Size of the stream 
in bytes. 


) LONG; 


Example: 


file nSStream; 


function () := 
VAR size LONG; 


{ 


size := nSsize(file); 
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n$trunc 


nStrunc function 


n$trunc truncates the stream to the current position. — 


Some nosls do not support n$trunc. 


fetion oem [ie 


inStrunc ( 
s nS$Stream 


be 


Stream to truncate. 


Example: 


file nSStream; 


function () := 


{ : 
nStrunc(file); 
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n$status 


Description 


n$status includes a type, n$Status, that defines the 
different stream statuses, and a function, n$status, that 
returns the current status of a stream. 


n$Status type 


n$ Status is defined as follows: 


FTYPDEF nSStatus SETW ( 
nSbusy, Stream is busy with another 1/0. 


Stream is positioned between 
logical records. 


nSEOR, 


Stream is positioned at the end | 
of the stream. 

Note: Positioned just past the 
last character of the stream. 


nSEOF 
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n$status function 
n$status returns the current status of the stream. 
All nosls support n$status. 


nSstatus ( 
s n$Stream 


{Stream to check the 
status. 


Status of the 
stream. 


) n$Status; 


Example: 


file nSStream; 


function () := 
{ 
LOOP { 
WHILE ~ ( nSstatus(file) && nSEOF ); 
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n$flush 
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n$flush function 
n$flush flushes any internal buffers used by the stream. 
e Read buffers are simply marked empty, and 
e Write buffers are dumped to the underlying stream or 


device. 


All nosls support n$flush. 


nSflush ( 
s nSStream Stream to flush. 


a3 


Example: 


out nSStream; 


function () := 


{ 
nSflush(out); 
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n$close 


n$close function 


n$close completes all pending operations and closes the 
stream. Any storage that was allocated by the nosl is 
released. 


All nosls support n$close. 


nSclose ( 
s nSStrean, Stream to close. 


mode BYTE 'RMS close mode unless otherwise 


}stated by the particular nosl. 


out nSStream; 


function () := 


{ 
n$close(out, SCMCHOP) ; 
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n$format 
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Description 


The n$format function outputs formatted data to an output 
stream. 


n$format is actually a macro that calls other NOSL 
functions to perform various operations. 


n$format function 
n$format outputs formatted data to the output stream. 


Since n$format is a macro that calls n$write and n$flush, 
any nosl that does not support n$write and n$flush will not 
support n$format. 


anSformat ( 
s nSstreanm, Stream to write formatted 


data to. 


[ other parameters ] |Up to eight nS$format 
output specifications. 


» 
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n$format output specifications 


There are several n$format output specifications. Use the 
following table to select the type of formatted output 
needed for your data. 


output an octal number 
output a hexadecimal number 


output a real number 


n$flush the output stream 
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Single character output 


The "C" output specification outputs up to seven single 
characters. 


Note: If more than one character is specified, the 


characters are stored in a temporary array and written with 
a single n$write. 


C ¢ 
character CHAR, A single character to output to the 
output stream. 


{ characters ] Up to six more characters to output 
to the output stream separated by 
commas. 


Example: 


function (v, h BYTE) := 
{ 
nS$format(out, C( SCP, v+SWSTL, h+SWSLC, '*' ) ); 
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String output 


The "S" output specification outputs an "object in memory" 


(typically an array of characters but can be an INT, 
STRUCT, etc). 


5S ¢ , 
object in memory, |The string or object to output. 
Note: nSformat expects the 


actual object and not the address 
of the object. 


[ length UNSIGNED ] |Number of characters to output. 
Note: If this parameter is not 
specified, SIZEOF the object will 
be used as the length. 


Example: 


function () := 
VAR STATIC array [] CHAR := '‘'Hello'; 
{ 


nS$format(out, S( array ) ); 
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Quoted string output 


The quoted string output specification outputs the 
characters within single quotation marks. 


| 
Quoted string to output. 


nSformat Syntax 


function () := 


{ 


nSformat(out, ‘Hello’ ); 
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Decimal number output 


The "D" output specification outputs the decimal value of a 
number in ASCII format. 


D ¢ 


Number to output in decimal. 
Note: Negative numbers are output 
with a preceding minus sign. 


number LONG, 


Minimum length of the field where 
the number is output. 

Note: The number is right 
justified and padded with blanks 
on the left if it is smaller than 
the minimum length. 


[ length UNSIGNED } 


function () := 


{ 


nS$format(out, D¢ 4000, 10 ) ); 
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Octal number output 


The "O" output specification outputs the octal value of a 
number in ASCII format. 


O ¢ 
number LONG, Number to output in octal. 
Note: The number is treated as an 
unsigned LONG. That means a -l 
will be output as a 037777777777. 
The number may be cast to a BYTE 
or UNSIGNED to suppress this. 


[ length UNSIGNED ] |Minimum length of the field where 


the number is output. 

Note: The number is right 
justified and padded with zeros on 
the left if it is smaller than the 
minimum length. 


function () := 
{ 
n$format(out, O¢ 4000, 10 ) ); 


Result: 


|.0000007640 
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Hexadecimal number output 


The "H" output specification outputs the hexadecimal 
value of a number in ASCII format. 


H ¢ 
number LONG, Number to output in hexadecimal. 
Note: The number is treated as an 
unsigned LONG. That means a -l 
will be output as a FFFFFFFF. The 
number may be cast to a BYTE or 
or UNSIGNED to suppress this. 


[ length UNSIGNED ] {Minimum length of the field where 


the number is output. 

Note: The number is right 
justified and padded with zeros on 
the left if it is smaller than the 
minimum length. 


function () := 


{ 
nSformat(out, H( 4000, 10 ) ); 


Result: 


| 0000000FA0 
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Real number output 


There are three real number output directives. Use the 
following table to determine which real output directive to 
use. 


output a real number using scientific 
inotation 


output a real number using the shorter of 
the two notations, scientific and floating 
point 


| 
output a real number using floating point 3-25 
notation 

i 
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Real number output in "e" format 


The "Re" output specification outputs a real number in 


ASCII scientific notation. 
Real number to output in the form 


Re ( 
[-]m.nnnnnnE[-]xxx 


number DOUBLE, 


Number of digits to output 
following the decimal point. 


places UNSIGNED, 


[ length UNSIGNED ] {Minimum length of the field where 
the number is output. 

Note: The number is right 
justified and padded with blanks 
on the left if it is smaller than 


the minimum length. 


function () 


{ 


nSformat(out, Re( 1234.56789, 2, 20 ) ); 


Result: 


| LZOES 
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Real number output in “f" format 


The "Rf" output specification outputs a real number in 
ASCII floating point notation. 


Rf ( 
number DOUBLE, Real number to output in the form 
[-]mmm.nnnnnn 


places UNSIGNED, Number of digits to output 
following the decimal point. 


{ length UNSIGNED ] |Minimum length of the field where 


the number is output. 

Note: The number is right 
justified and padded with blanks 
on the left if it is smaller than 
the minimum length. 


Ul 


function () 


{ 
nSformat(out, RF( 1234.56789, 2, 20 ) ); 


Result: 


| 1234.57 
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Real number output in “g" format 


The "Rg" output specification outputs a real number in the 
shorter of the two ASCII notations, scientific and floating 
point. 


Rg ( 
) number DOUBLE, /Real number to output in the "e" 
or "f£'' format, whichever is 
shorter. 
Note: Does not output 
insignificant zeros. 


places UNSIGNED, Number of digits to output 
following the decimal point. 


[ length UNSIGNED ] |Minimum length of the field where 
the number is output. 
Note: The number is right 
justified and padded with blanks 
on the left if it is smaller than 
the minimum length. 


function () := 
{ 
nSformat(out, Ref 1234.56789, 2, 20 ) ); 


Result: 


| Li ZoE3 
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New line output 


The "LN" output specification outputs a single $LEOR. 


rr 


function () := 


{ 


nSformat(out, LN ); 


Flush n$format internal buffers 


The "F" output specification causes an n$flush to be 
performed on the output stream. 


function () := 


{ 


nS$format(out, F ); 


Chapter 3. TLE. INOS: FUNG DONS cheae a 


DAS bs “USER 35: “GU LD 


DOS Oe Oa 


Chapter 4. 


THE NOSLS 
OVERVIEW 


aaa eee 
Introduction 


This chapter contains a description of the individual nosls 
and a guide for selecting a nosl. 


Each nosl is a tool 


The philosophy of NOSL is that of a toolbox. Each nosl 
described in this chapter is a small, easy to understand 
tool, designed to handle a particular job. 


Parameterization of the NOSL open call 


Each of the nosls in this chapter will include a description 
of their nosl open calls. Several parameters in each nosl 
open call are optional. 


Optional parameters are enclosed in square brackets for 
identification in the function diagrams. They may be 
ignored by omitting them completely, or by replacing them 
with a comma if a later parameter is to be specified. 
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NUMBER type 


As mentioned in the previous chapter, NOSL defines a 
type, NUMBER, which represents the addressable memory 
area of a machine. In this chapter, this type is used to 
define the buffer size in the NOSL open function. 


On machines with 16 bit pointers, NUMBER is defined as 
follows: 


TYPDEF NUMBER UNSIGNED; |Addressable memory area of a 
machine. 


Note: On machines with 32 bit pointers, NUMBER is defined 
as LONG. 


NOSL open error parameters 


The NOSL open function contains two optional parameters 
(eF and eD) that may be used to customize error handling 
for each nosl. See the Error Handling chapter for further 
details. 
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SELECTING A NOSL 
cnn 


Overview 


This section contains the description of a function that 
determines the device kind of an RMS filename, anda table 
of the different nosls available. 


n$fKind function 
n$fKind returns the device kind of an RMS filename. 


This function is useful for programs that do not know what 
kind of input or output device to read or write until run 
time. 


Function Syntax 


nSfKind ( 
sfentP a SSFENT, Address of the file 
entry table of the 
file to determine 
the device kind. 


pSubKind ~ BYTE 1], Address of a Initialized 
byte. with subkind 


eF a nSErrorFunc |], |Address of error 
function. 


eD a nSErrorData ] Address of error 
data. 


) BYTE; RMS device 
kind. 


Example: 
SDKDISK 
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SELECTING A NOSL 


n$fKind function (continued) 


Example: The following program segment scans an output 
device from the command line and calls an appropriate 
function based upon the device kind returned. 


fileSpk SFILESPK := { 
{ ‘IN oo eg tae Zr 


SFILNAMR, SNOADR, &'TEXT' ,&' : 
by 


function () := 
VAR dK BYTE; 
{ 
IF SSCANFLS(&fileSpk, 1) && DSCFLAG THEN SERMSG(); 
dK := nSfKind(&fileSpk.SFSOSFT ) ; 
CASE dK { 
SDKPIPE : openPipe(); 
SDKPRINT : openPrinter(); 
DEFAULT : error(); 
} 5 
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SELECTING A NOSL 


Which nosl? 


Use the following table to determine which nos! to use. 


input/output to a binary disk file|Disk, or 
DiskId nosl. 


input from the workstation Workstation 4-24 
input nosls. 


~_ 


rf 
4. 


SE | 
% 
od | om | 

a) 


12 
#15 
17 
-19 
ayes 


4. 
4 
4. 


Workstation 
output nosls. 


. 


output to the workstation 


7 
1 
Ww 
~ 


4-43 
4-46 
4-48 
4-50 
-52 
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Disk NOSL 


Introduction 
NOSL provides the Disk nosl for input and output of binary 
data to a disk file. 

End-of-file pointer 


The Disk nosl uses the RMS end-of-file pointer to define 
the end-of-file rather than the first occurrence of a $LEOF 
character. 


NOSL function support 


The Disk nosl supports all of the NOSL functions. 
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Disk NOSL 


Disk nos! n$open 


This function diagram describes the parameterization of 
the n$open for the Disk nosl. 


Function Syntax 


nSopen ( 
Disk, Binary disk I/O stream 
indicator. 


eF a nSErrorFunc ], Address of error 
function. 


eD a nSErrorData |], 


sfentP a SSFENT, Address of the file entry 
table of the file to 
open or create. 


formatP a BYTE 1], Address of a byte. 
Specifies file format if 
creating a file. 
Note: Defaults to 
SFFMTTXT. 


mode BYTE |], RMS open mode. 
Note: Defaults to 
SOMREAD . 


bufSize NUMBER 1], Size of buffer to use in 
bytes. 
Note: Defaults to 2048. 


openPTP a SOPENPTP ] |Address of an open 
parameter table. 
Note: Sector length and 
increment default to 200. 
formatP takes precedence 
over openPTP format. 


) n$Stream; Opened 
stream. 
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Disk NOSL 


Disk nos! n$open (continued) 


Example: 


out nS$Stream; 


fileSpk SFILESPK := { 
{ "OUT ns ' a q * ' ' io 
SFILNAMR, SNOADR, &'TEXT' ,&' : 
by 


function () := 

{ 
IF SSCANFLS(&fileSpk, 1) && DSCFLAG THEN SERMSG(C); 
out := nSopen(Disk,,, &fileSpk.SFSOSFT,, SOMPREP) ; 
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Diskld NOSL 
one ee 
Introduction 
In addition to the Disk nosl, NOSL provides the DiskId nosl 


for input and output of binary data to a disk file that is 
already open. 


The file is opened by FAVID 


The DiskId nosl opens the disk file by its file access 
variable (FAVID). 


Uses for the Diskld nos! 
The DiskId nos] is useful for 
e opening several nosls on the same file, or 


e keeping several files open while using a single set of 
buffers. 


NOSL function support 


The DiskId nosl supports all of the NOSL functions. 
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Diskld NOSL 


NOSL function results 


The following NOSL functions have unique results when 
used with the DiskId nosl. 


nsclose |closes the nosl, but not the file. 


Diskld nos! n$open 


This function diagram describes the parameterization of 
the n$open for the DiskId nosl. 


nSopen ( 
DiskId, Binary disk FAVID I/0 
stream indicator. 


eF a nSErrorFunc ], |Address of error function. a 


eD a nSErrorData ], |Address of error data. 


id UNSIGNED, File access variable ID 
of an open file. 


bufSize NUMBER ] Size of buffer to use in 
bytes. 
Note: Defaults to 2048. 


) n$Stream; 


stream. 
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Diskld NOSL 


Diskld nosl n$open (continued) 


Example: This program segment opens two nosls on one 


disk file. 
FI SPFDB; 
fileSpk SFILESPK := { 
{ "OUT ' ‘ ’ ' , i] ’ ' ' v } : 
SFILNAMR, SNOADR, &' TEXT’ ,&' : 


5 


openPT SOPENPT := { 
&fI, 
&fileSpk.SFSOSFT.SSFTENV[0O], 
&<SNAMEEXT>fileSpk.SFSOSFT.SSFTNAM 


h; 


inl nSStream; 
in2 nSStrean; 


function () := 
VAR fav UNSIGNED; 
{ 
IF SSCANFLS(&fileSpk, 1) && DSCFLAG THEN SERMSGC); 
IF SOPEN(CSOMREAD, &openPT) && DSCFLAG THEN 
SERMSG( ) ; 
fav := openPT.SOTPFDBA.SPFVID; 
inl := nSopen(DiskId,,, fav, 4096); 
in2 := nSopen(DiskId,,, fav, 256); 


Chapter 4. THE NOSES ae | 


DiskR NOSL 


Introduction 
NOSL provides the DiskR nosl for reading data from a disk 
file. It is a read only version of the Disk nosl. 

NOSL function support 


The DiskR nosl supports all of the NOSL functions except 
e n$write, 


e n$trunc, and 
e n$format. 
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DiskKR NOSL 


DiskR nosl n$open 


This function diagram describes the parameterization of 
the n$open for the DiskR nosl. 


Function Syntax 


nSopen ( 


DiskR, 


eF a nSErrorFunc ], 


eD a nSErrorData |], 


sfentP a SSFENT, 


formatP a BYTE ], 


mode BYTE |], 


bufSize NUMBER ], 


openPTP a SOPENPTP |] 


) nS$Stream; 


Chapter 


Binary disk input 
stream indicator. 


Address of error 
function. 


Address of error 
data. 


Address of the file 
entry table of the 


file to open. 


Address of a byte. 


RMS open mode. 


Note: Defaults to 


SOMREAD. 


in bytes. 
Note: Defaults to 


2048. 


Address of an open 
parameter table. 
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File format 
of file 


Size of buffer to Z_ 


Opened 
stream. | 


AS 13 
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DiskR nosl n$open (continued) 


Example: 


in nS$Stream; 


fileSpk SFILESPK := { 
{ "IN os q - ' a ' ' he 
SFILNAMR, SNOADR, ra 2 a a ay 


}; 


function () := 

{ 
IF SSCANFLS(&fileSpk, 1) && DSCFLAG THEN SERMSG(); 
in := nSopen(DiskR,,, &fileSpk.SFSOSFT,, ,4096); 
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VirFil NOSL 
TE eee 
Introduction 


NOSL provides the VirFil nosl as a virtual file facility. The 
VirFil nos] simulates a virtual file for both input and 
output. 


Definition of a virtual file 


A virtual file is a file that looks and acts like a real file, 
except it is maintained in memory. Input and output to a 
virtual file is therefore much faster than a disk file. 


Note: The memory used by a virtual file is released by the 
virtual file handler when the virtual file is closed. If more 
than one virtual file is in use, the memory will not be 
released until all of the virtual files have been closed. 


The spill file 
If the virtual file runs out of memory, a "spill file" is 
created on disk to hold the data that did not fit in memory. 
Multiple virtual files will all use the same spill file if they 


run out of memory. 


Note: NOSL will delete the spill file when all virtual files 
are closed. 


Improving performance 


VirFil may realize a performance improvement by opening 
a BufPag nosl over the VirFil nosl. 
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VirFil NOSL 


NOSL function support 


The VirFil nosl supports all of the NOSL functions. 


VirFil nosl nSopen 


This function diagram describes the parameterization of 
the n$open for the VirFil nosl. 


Virtual binary disk I/O 
stream indicator. 


[ eF a nSErrorFunc ], |Address of error function. Ll 
[ eD a nSErrorData ] Address of error data. a 


) n$Stream; Opened 
stream. 


Example: 


virtual nSStream; 


function () := 


{ 


virtual := nSopen(VirFil); 
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BufPag NOSL 
(a ep aa OE I TET 
Introduction 


NOSL provides the BufPag nosl for buffering the data input 
or output from another nosl. 


Performance improvement 


The BufPag nos] is useful for improving performance by 
reducing the number of operations of another nosl. 


Note: The potential improvement in performance is bought 
at the price of memory allocated from your address space. 


NOSL function support 


The BufPag nosl supports all of the NOSL functions except 
n$trunc. 


NOSL function results 


The following NOSL functions have unique results when 
used with the BufPag nosl. 


inction Results 


nSopen the position of the nosl stream is the same 
as the position of the underlying stream. 

nSclose the nosl is closed, but the underlying stream 
is not. 
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BufPag NOSL 


BufPag nosl n$open 


This function diagram describes the parameterization of 
the n$open for the BufPag nosl. 


nSopen ( 
Buf Pag, Page aligned buffer stream 
indicator. 


eF a nSErrorFunc ], |Address of error function. Ed 
eD a nSErrorData ], |Address of error data. i 3 


under nSStrean, Stream to buffer. a 


bufSize NUMBER ] Size of buffer to use in 
bytes. 
Note: Defaults to 256. 


) n$Stream; Opened 
stream. 


Example: 


buff nSStream; 


function () := 
VAR virtual nSStream; 
{ 
virtual := nSopen(VirFil); 
buff := nSopen(BufPag,,, virtual, 512); 
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Decomp NOSL 
SR RR NE PRE NN 
Introduction 
NOSL provides Decomp as a text decompression nos] for 


decompressing text read in from one of the binary disk 
nosis. 


End-of-file pointer 
The Decomp nos] defines the end-of-file as the position 


specified by the RMS end-of-file pointer or the first 
occurrence of a $LEOF character, whichever comes first. 


NOSL function support 
The Decomp nosl supports all of the NOSL functions except 
e n$write, 


e n$trunc, and 
e n$format. 
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Decomp NOSL 


NOSL function results 


The following NOSL functions have unique results when 
used with the Decomp nosl. 


nSopen the position of the nosl stream is the same 
, as the position of the underlying stream. 


nSread Stops reading if a SLEOR character or the 
maximum number of characters is read. 
sets the nSEOF status but does not return 
the SLEOF if a SLEOF terminates the read 
rather than a SLEOR. The nSEOR status is 
not set in this situation. 


nStell only valid when nSEOR status is set. 
returns position of SLEOF if current 
position and SLEOF are separated by SLDELs 
or SLEOBs. 
nSstatus |returns nSEOF status if current position and 
SLEOF are separated by SLDELs or SLEOBs. 


force nSEOR status. 


men”; nosl is closed, but the underlying stream 
is not. 
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Decomp NOSL 


Decomp nosl n$open 


This function diagram describes the parameterization of 
the n$open for the Decomp nosl. 


nSopen ( 
Decomp, Text decompression stream 


indicator. 


[ eF a nSErrorFunc ], 


{ eD a nSErrorData 1], 
under nSStream 


) nSStream; 


Example: 


in nSStream; 
decomp nSStream; 


fileSpk S$FILESPK := { 
{ "IN tes ' ae y Pes ' q }, 
SFILNAMR, SNOADR, &' TEXT", &' 


be 


function () := 


{ 
IF SSCANFLS(&fileSpk, 1) && DSCFLAG THEN SERMSG(C); 


in := nSopen(DiskR,,, &fileSpk.SFSOSFT,, , 4096) ; 
decomp := nSopen(Decomp,,, in); 
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CmpOut NOSL 
re ee eee 
Introduction 


NOSL provides CmpOut as a text compression nosl for 
writing compressed text to one of the binary disk output 
nosls. 


NOSL function support 


The CmpOut nosl supports all of the NOSL functions except 
n$read. 


NOSL function results 


The following NOSL functions have unique results when 
used with the CmpOut nosl. 


nSopen the position of the nosl stream is the same 
as the position of the underlying stream. 


nStell forces a nS$flush before performing normal 
nSseek operations. 

nSsize 
nS$trunc 


2 nosl is closed, but the underlying stream 
is not. 
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CmpOut NOSL 


CmpOut nos! n$open 


This function diagram describes the parameterization of 
the n$open for the CmpOut nosl. 


nSopen ( 
CmpOut, Text compression stream 
indicator. 


[ eF a nSErrorFunc ], |Address of error function. —_ 


{ eD a nSErrorData ], |Address of error data. 


under nS$Stream Text stream to output 
compressed text to. 


) n$Stream; Opened 
stream. 


Example: 


out nS$Stream; 
cmp nS$Stream; 


fileSpk SFILESPK := { 
{ "OUT a ' a ' a ' v }, 
SFILNAMR, SNOADR, & 'TEXT' ,&' ' 
bs 


function () := 


{ 
IF SSCANFLS(&fileSpk, 1) && DSCFLAG THEN SERMSG(C); 
out := nSopen(Disk,,, &fileSpk.SFSOSFT,, SOMPREP); 
cmp := nSopen(Cmp0Out,,, out); 
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WORKSTATION INPUT NOSLS 


Introduction 


NOSL provides several input nosls tc input data from the 
workstation. 


The workstation input nosls are WSIn, ChaIn, BWSIn, and 
BChaIn. 


Unbuffered and buffered input 


The workstation input nosls can be separated into 
unbuffered, WSIn and ChalIn, and buffered, BWSIn and 
BChalIn input nosls. When doing an n$read, 


e the unbuffered nosls will read up to 81 characters from 
the workstation. They will accept no more than the 
number of characters specified by the n$read. 

e the buffered nosls will read up to 81 characters to fill 
the buffer and then return the number of characters 
specified by the n$read. If more characters were 
entered into the buffer than were specified by the 
n$read, the characters are retained in the buffer and 
returned on subsequent reads. 


Predefined stream constants 


Each of the workstation nosls have a corresponding 
predefined stream constant. These constants may be used 
as the stream parameter to the NOSL functions. 


The only reason to actually "open" the workstation nosls, 


instead of using these stream constants, is to specify an 
optional parameter with a value other than their defaults. 


4-24 DAS is. USAR 1S: “GUE E FOO UI Oil 


WORKSTATION INPUT NOSLS 


NOSL function support 


The workstation input nosls support all of the NOSL 
functions except 


e n$write, 

e n$tell, 

e n$seek, 

e n$size, 

e n$trunc, and 
e n$format. 


Which nosl? 


Use the following table to determine which nos} to use. 


input data from either the keyboard |ChalIn. 4-28 
or chain file if chaining is active 
+30 


buffer input from either the keyboard 
or chain file if chaining is active 
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WSIn nos! 


The WSIn nosl inputs from the keyboard. 


n$WSiIn constant 


n$WSIn is a constant that is available for you to use. 


nSWSIn nSStream; Predefined WSIn input stream. 


Example: 


function () := 
VAR on BYTE; 
s [81] CHAR; 


n := nSread(nSWSIn, &s[0], SIZEOF s); 
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WORKSTATION INPUT NOSLS 


WSiIn nosl n$open 


This function diagram describes the parameterization of 
the n$open for the WSIn nosl. 


Note: This function will return a stream with the same 
value as the n$WSIn constant described above. 


nSopen ( 
WSIn, Workstation input stream 
indicator. | 


eF a nSErrorFunc ], |Address of error function. 
eD a nSErrorData |], |Address of error data. a 


noEnter BOOLEAN ] TRUE disables a SLEOR 
from being written to the 
workstation every time one 
is read from the keyboard. 


Note: Default is FALSE. 


) n$Stream; Opened 
stream. 


Example: 


in nSStream; 


function () := 
VAR n BYTE; 
s [81] CHAR; 


in := nSopen(WSIn,,, TRUE); 
n := nSread(in, &s[0], SIZEOF s); 
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Chaln nosl 


The ChaIn nosl inputs from either the keyboard or chain 
file if chaining is active. 


n$Chaln constant 


n$ChaIn is a constant that is available for you to use. 


Predefined ChaIn input stream. 


function () := 
VAR on BYTE; 
s [81] CHAR; 


{ 
n := nSread(nSChaIn, &s[0], SIZEOF s); 
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WORKSTATION INPUT NOSLS 


Chain nosl n$open 


This function diagram describes the parameterization of 
the n$open for the ChalIn nosl. 


Note: This function will return a stream with the same 
value as the n$ChalIn constant described above. 


nSopen ( 
ChaIn, Chain input stream 
indicator. 


[ eF a nSErrorFunc ], {Address of error function. — 
[ eD a nSErrorData ], |Address of error data. Lo 


[ noEnter BOOLEAN ] TRUE disables a SLEOR 
from being written to the 
workstation every time one 
is read from the keyboard 
or chain file. 
Note: Default is FALSE. 


) n$Stream; Opened 
stream. 


Example: 


in nSStream; 


function () := 
VAR n BYTE; 
s [81] CHAR; 


in := nSopen(ChaIn,,, TRUE); 
n := nSread(in, &s[0], SIZEOF s); 
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BWSIn nos! 


The BWSIn nos! buffers input from the keyboard. 


n$BWSIn constant 


n$BWSIn is a constant that is available for you to use. 


nSBWSIn nSStreamn; Predefined BWSIn input stream. 


Example: 


function () := 
VAR on BYTE; 
s [81] CHAR; 


{ 


~ 
I 


nSread(nSBWSIn, &s[0], SIZEOF s); 
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WORKSTATION INPUT NOSLS 


BWSIn nosl n$open 


This function diagram describes the parameterization of 
the n$open for the BWSIn nosl. 


Note: This function will return a stream with the same 
value as the n$BWSIn constant described above. 


nSopen ( 
BWSIn, 


Buffered workstation input 
stream indicator. 


Address of error function. —_ 
Address of error data. a 


Opened 
stream. 


[ eF a nSErrorFunc ], 


[ eD a nSErrorData ] 


) nSStream; 


Example: 


in nSStrean; 


function () := 
VAR on BYTE; 
s [81] CHAR; 


in := nSopen(BWSIn, &errorF); 
n := nSread(in, &s[0], SIZEOF s); 
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BChain nos! 
The BChalIn nos! buffers input from either the keyboard or 
chain file if chaining is active. 

n$BChalin constant 


n$BChalIn is a constant that is available for you to use. 


nS$BChaIn nSStream; Predefined BChaIn input stream. 


Example: 


function () := 
VAR on BYTE; 
s [81] CHAR; 


n = 
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{ 
nSread(nSBChaIn, &s[0], SIZEOF s); 


WORKSTATION INPUT NOSLS 


BChalIn nos!| n$open 


This function diagram describes the parameterization of 
the n$open for the BChaIn nosl. 


Note: This function will return a stream with the same 
value as the n$BChaIn constant described above. 


nSopen ( 
BChaIn, Buffered chain input 
stream indicator. 


[ eF a nSErrorFunc ], |Address of error function. 
[ eD a nSErrorData ] Address of error data. 


) n$Stream; 


Example: 


in nSStrean; 


function () := 
VAR on BYTE; 
s [81] CHAR; 


in := nSopen(BChaIn, &errorF ); 
n := nSread(in, &s[0], SIZEOF s); 
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WORKSTATION OUTPUT NOSLS 
EE aE a 
Introduction 


NOSL provides several output nosls to output data to the 
workstation. | 


The workstation output nosls are WSOut, Line25, and 
LogOut. 


Common buffer 


The workstation output nosls share a common buffer. 
This buffer is flushed when 


e the buffer is full, 

e ann$read operation is performed by the n$WSIn or the 
n$ChalIn nosl, 

e an $LEOR character is written, or 

e awrite is performed on one of the other two output 
nosls. 


Note: The common buffer is initialized with a $NL (newline 


character) which causes the first output to the screen to be 
written on its own line. 
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Writing $LEORs 


When a $LEOR is written to one of the workstation output 
nosis, 


e the common buffer is flushed first, and 
e a $NL is left as the first character in the common buffer. 


Note: This treatment of $LEORs enables you to write to the 
workstation exactly as if it was a file. 


WSIO control code support 


The following WSIO control codes are not supported by the 
workstation output nosls. 


e $WSIS, 

e $WSISI, 

e $WSIN, 

e $WSINI, 

e $WSIDOCS, and 
e $WSCONED. 


Predefined stream constants 


Each of the workstation nosls have a corresponding 
predefined stream constant. These constants may be used 
as the stream parameter to the NOSL functions. 


The only reason to actually "open" the workstation nosls, 


instead of using these stream constants, is to specify 
optional parameters with values other than their defaults. 
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NOSL function support 


The workstation output nosls support all of the NOSL 
functions except 


e n$read, 
® n$tell, 
e n$seek, and 
n$size. 


Note: n$trunc is supported but performs no function. 


Which nosl? 


Use the following table to determine which nosl to use. 


foutput to the workstation screen WsOut. 


output to a pseudo 25th line on the |Line25. 4-39 
workstation screen 

output to the workstation screen LogOut. 4-4] 
and log file if logging is active 
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WSOut nos! 


The WSOut nos! outputs to the workstation screen. 


n$WSOut constant 


n$WSOut is a constant that is available for you to use. 


nSWSOut nSStream; Predefined WSOut output stream. 


function () := 


{ 


n$format(nSWSOut, 'Welcome to NOSL', LN); 
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WSOut nosl n$open 


This function diagram describes the parameterization of 
the n$open for the WSOut nos. 


Note: This function will return a stream with the same 
value as the n$WSOut constant described above. 


Workstation output stream 
{indicator. 


Address of error function. _ 
Address of error data. Ld 


Opened 
stream. 


[ eF a nSErrorFunc ], 


[ eD a nSErrorData ] 


) n$Stream; 


Example: 


out nSStream; 


function () := 


{ 
out := nSopen(WSOut, &errorF ); 
nSformat(out, 'Welcome to NOSL"', LN); 
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Line25 nosl 


The Line25 nosl outputs to a pseudo 25th line on the 
workstation screen for status and operator entertainment 
messages. 


After a message has been displayed by this nosl, the 
common buffer is primed with a $EEOL (erase to end of 
line) which will cause the message to disappear when 
something is written by one of the other workstation 
output nosls. 


n$Line25 constant 


n$Line25 is a constant that is available for you to use. 


Predefined Line25 output stream. | 


function () := 


{ 


nSformat(nSLine25, ‘Waiting for a message', LN); 
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Line25 nos! n$open 


This function diagram describes the parameterization of 
the n$open for the Line25 nosl. 


Note: This function will return a stream with the same 
value as the n$Line25 constant described above. 


nSopen ( 
Line25, 


Pseudo 25th line output 
stream indicator. 


Address of error function. — 
Address of error data. a 


Opened 
stream. 


{ eF a nSErrorFunc ], 


[ eD a nSErrorData ] 


) n$Stream; 


Example: 


out nSStream; 


function () := 


{ 
out := nSopen(Line25, &errorF); 
n$format(out, 'Waiting for a message', LN); 


DASE USERS. GUIDE SO SO HOF 


WORKSTATION OUTPUT NOSLS 


LogOut nos! 


The LogOut nosl outputs to the workstation screen and log 
file if logging is active. 


n$LogOut constant 


n$LogOut is a constant that is available for you to use. 


Description 


Predefined LogOut output stream. 


function () := 


{ 
nS$format(nSLogOut, 'Processing labels', LN); 
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WORKSTATION OUTPUT NOSLS 


LogOut nos! n$open 


This function diagram describes the parameterization of 
the n$open for the LogOut nosl. 


Note: This function will return a stream with the same 
value as the n$LogOut constant described above. 


Friese mei 


InSopen ( 
LogOut, 


Log output stream 
indicator. 


Address of error function. = 
Address of error data. P| 


Opened 
stream. 


[ eF a nSErrorFunc ], 


{ eD a nSErrorData ] 


) n$Stream; 


Example: 


out nS$Stream; 


function () := 

{ 
out := nSopen(LogOut, &errorF); 
nS$format(out, ‘Processing labels', LN); 
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Print NOSL 
ee 
Introduction 


NOSL provides the Print nos] to output data to a printer. 


NOSL function support 
The Print nosl supports all of the NOSL functions except 


e n$read, 

@ n$tell, 

e n$seek, 

e n$size, and 
e n$trunc. 
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Print NOSL 


Print nos!| n$open 


This function diagram describes the parameterization of 
the n$open for the Print nosl. 


nSopen ( 
Print, Printer output stream 
indicator. 


eF a nSErrorFunc ], Address of error 
function. 


eD a nSErrorData J], 


sfentP a SSFENT, Address of file entry 
table to open. 


bufSize NUMBER ], Size of buffer to use in 
bytes. 
Note: Defaults to optimum 
size declared by the 
printer. 


offLineF ~ DSCALLF ] |Address of a function to 
call if the printer is 
offline or out of paper. 
Note: Will display 
"Printer not ready" 
through Line25 nosl if 
function not specified. 


) n$Stream; Opened 
stream. 
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Print NOSL 


Print nosl n$open (continued) 


Example: 


prt nSStream; 

prtSFI SSFENT := { 
"PRT ". 'SLP a f° ere : 
A 


function () := 


prt := nSopen(Print,,, &prtSFT); 
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Pipe NOSL 


Introduction 


NOSL provides the Pipe nos] to input and output data toa 
pipe. 


NOSL function support 


The Pipe nosl supports all of the NOSL functions except 


® n$tell, 

@ n$seek, 

e n$size, and 
e n$trunc. 


NOSL function results 


The following NOSL functions have unique results when 
used with the Pipe nosl. 


nSread e causes a flush of any pending write data. 

e stops after the last character in the pipe 
message or the maximum number of characters 
is read. If there is no current pipe 
message when a nSread is performed, an RMS 


physical read is performed on the pipe. 


nSwrite discards any remaining read data. 
nS$format 


nS$status |e returns a nSEOR status when an entire pipe 
message has been read. 
e There is no nSEOF status for pipes. 
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Pipe NOSL 


Pipe nosI n$Sopen 


This function diagram describes the parameterization of 
the n$open for the Pipe nosl. 


nSopen ( 
Pipe, Pipe I/O stream indicator. 


eF a nSErrorFunc ], |;Address of error function. 
eD a nSErrorData ], |Address of error data. 


sfentP a SSFENT, Address of file entry 
table to open. 


bufSize NUMBER 1, Size of buffer to use in 
bytes. 
Note: Defaults to 256. 


timeout BYTE ] Number of seconds before 
a pipe operation will time 
out. 
Note: Default is SFOREVER. 


) n$Stream; Opened 
stream. 


Example: 


pipe nSStream; 

pipeSFT SSFENT := { 
"PIPE ", 'MY PIPE NAME', 'PIPE', ' ' 
}; 


function () := 


{ 
pipe := nSopen(Pipe,,, &pipeSFT); 
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Split NOSL 
ER aS i a I Ss 
Introduction 


NOSL provides the Split nos] for duplicating output to two 
other nosls. 


NOSL function support 
The Split nos] supports all of the NOSL functions except 


e n$read, 

® n$tell, 

e n$seek, and 
e n$size. 


NOSL function results 


The following NOSL functions have unique results when 
used with the Split nosl. 


nstrunc [performs nStrunc on both "under" nosls. 
nsstatus | always returns 0. 
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Split NOSL 


Split nos! n$open 


This function diagram describes the parameterization of 
the n$open for the Split nosl. 


Function Syntax 


nSopen ( 
Split, Output splitter stream 
indicator. 


eF a nSErrorFunc ], {Address of error function. 
eD a nSErrorData ], {Address of error data. 


underl nSStream, First stream to split the 
output data to. 


under2 n$Stream Second stream to split the 
output data to. 


) n$Stream; 


Example: The following program segment opens a split 
nosl that will duplicate output to a disk file and the 
workstation screen. 


outD nSStream; 
out nS$Stream; 


fileSpk SFILESPK := { 
{ ‘OUT - ' i ' yy ' ' }, 
SFILNAMR, SNOADR, &'TEXT',&' : 
= 


function () := 

{ 
IF SSCANFLS(&fileSpk, 1) && DSCFLAG THEN SERMSG(); 
outD := nSopen(Disk,,, &fileSpk.SFSOSFT,, SOMPREP) ; 
out := nSopen(Split,,, nSWSOut, outD); 
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Mem NOSL 


Introduction 
NOSL provides the Mem nos! for input and output to a block 
of memory. 

Uses for the Mem nos! 


The Mem nosl is primarily useful in conjunction with 
n$format for producing strings of text, as well as decimal, 
octal, hexadecimal, and floating numbers in memory. 


NOSL function support 


The Mem nos! supports all of the NOSL functions. 
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Mem NOSL 


Mem nos! n$open 


This function diagram describes the parameterization of 
the n$open for the Mem nosl. 


nSopen ( 
Men, Memory I/O stream 
indicator. 


[ eF a nSErrorFunc ], |Address of error function. 
[ eD a nSErrorData ], |Address of error data. 


buffP ~a BYTE, Address of the first byte 
of memory to use. 


buffSize UNSIGNED Number of bytes in the 
memory buffer. 


) n$Stream; Opened 
stream. 


Example: 


mem nSStream; 
buffer [80] BYTE; 


function () := 


{ 
mem := nSopen(Mem,,, &buffer[0], SIZEOF buffer); 
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Null NOSL 
aE ET Ta 
Introduction 


NOSL provides a nosl that will ignore all nosl operations. 


The Null nosl is a "do nothing" nosl. All operations to the 
Null nosl are ignored. 


Uses for the Null nosl 


The null nosl may be used as a replacement of an optional 
disk file or printer nosl. 


Example: A program that creates an output file if a certain 
option is specified on the command line can use the Null 
nosl if the option is not specified. This will alleviate 
having to check whether the option was set or not before 
every write, flush, etc... 


Predefined stream constant 
The Null nosl has a corresponding predefined stream 
constant. This constant may be used as the stream 
parameter to the NOSL functions. 
The only reason to actually "open" the Null nosl, 


instead of using this stream constant, is to specify an 
optional parameter with a value other than the defaults. 


NOSL function support 


The Null nos] supports all of the NOSL functions. 
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Null NOSL 


NOSL function results 


The following NOSL functions have unique results when 
used with the Null nosl. 


Porn pewe SCS—*SY 


returns 0 


nSopen 
nSwrite 
nStrunc 
nSflush 
nSclose 
nSformat 


nsstatus |returns status nSEOR and nSEOF. 


n$Null constant 


n$Null is a constant that is available for you to use. 


Predefined Null input stream. 


function () := 
VAR n BYTE; 
s [81] CHAR; 


{ 
n := nSread(nS$Null, &s{0], SIZEOF s); 
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Null NOSL 


Null nosI n$open 


This function diagram describes the parameterization of 
the n$open for the Null nosl. 


nSopen ( 
Null, Null stream indicator. 


[ eF a nSErrorFunc ], |Address of error function. 4 
[ eD a nSErrorData ], | Address of error data. a 


) n$Stream; Opened 
stream. 


Example: 


prt nSStream; 

prtSFT $SFENT : 
"PRT ‘, ‘SEP Pe UPR Sue ' 
b; 


{ 


optP SOPTION := { 'PRINT ', 0, SOPTVCLR, 0 }; 
optT SOPTTAIL := { SOPTTERM, 0 }; 


function () := 
{ 
IF SSCANOS(&optP) && DSCFLAG THEN SERMSG(); 
prt := optP.SOPTFLG && SOPTFDEF 
? nSopen(Print,,, &prtSFT) 
: nSopen(Null); 
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Chapter 5. 


NUMERIC SCANNERS 
OVERVIEW 


Introduction 


In addition to the actual NOSL I/O functions, several 
numeric scanning functions are provided in the NOSL 


library. 


Operate on strings in memory 


For reasons of both efficiency and flexibility, the numeric 
scanning functions deal with strings in memory rather than 
directly with streams. 


String and field scanners 


The numeric scanning functions are divided into two 
categories, 


e string scanners, and 
e field scanners. 


The following pages contain a detailed description of the 
numeric string and field scanners. 


Chapter as NUMERIC SCANNERS Sea 


STRING SCANNERS 


Description 


The string scanners parse a string in memory looking for a 
number. 


Numeric string format 


The numeric string may contain leading 


e blanks, 
e minus sign, and 
e in the case of hexadecimal, the characters "0X" or "Ox". 


The number must be terminated by a 
e space, 


e comma, or 
e $LEOR. 


String scanning functions 


Use the following table to determine which string scanning 
function to use. 
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STRING SCANNERS 


n$scanD function 


n$scanD converts a decimal string number into its 
numerical equivalent. 


Fete tom fiom 


nS$scanD ( 
ppCh aa CHAR, Address of a Points to the 
pointer to the terminator if a 
first character |number was 
in the string. found. Unchanged 
if no number. 


pStatus a BOOLEAN j|Address of a TRUE if a number 
boolean. was found. FALSE 
otherwise 


Decimal number 
scanned. 

Note: 0 if number 
was not found. 


Example: 


function (pC a CHAR) := 
VAR Status BOOLEAN; 
d LONG; 


d := n$scanD(&pC, &status); 
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STRING SCANNERS 


n$scanoO function 


n$scanO converts an octal string number into its numerical 
equivalent. 


Function Syntax 


nSscanoO ( 
ppCh aa CHAR, Address of a Points to the 
pointer to the terminator if a 
first character |number was 
in the string. found. Unchanged 
if no number. 


pStatus a BOOLEAN |Address of a TRUE if a number 
boolean. was found. FALSE 
otherwise 


Octal number 
scanned. 

Note: 0 if number 
was not found. 


Example: 


function (pC a CHAR) := 
VAR Status BOOLEAN; 
o LONG; 


o := nSscan0(&pC, &status); 
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STRING SCANNERS 


n$scanH function 


n$scanH converts a hexadecimal string number into its 
numerical equivalent. 


nSscanH ( 
ppCh aa CHAR, ~ Address of a Points to the 
pointer to the terminator if a 
first character |number was 
in the string. found. Unchanged 
if no number. 


pStatus ~ BOOLEAN |Address of a TRUE if a number 
boolean. was found. FALSE 
otherwise 


Hexadecimal 
number scanned. 
Note: O if number 
was not found. 


Example: 


function (pC a CHAR) := 
VAR Status BOOLEAN; 
h LONG; 


h := nSscanH(&pC, &status); 
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STRING SCANNERS 


n$scanR function 


n$scanR converts a real string number into its numerical 
equivalent. 


nS$scanR ( 
ppCh aa CHAR, Address of a |}Points to the 
pointer to the terminator if a 
first character |number was 
in the string. found. Unchanged 
if no number. 


pStatus a BOOLEAN |Address of a TRUE if a number 
boolean. was found. FALSE 
otherwise 


) DOUBLE; Floating point 
number scanned. 
Note: 0 if number 
was not found. 


Example: 


function (pC a CHAR) := 
VAR status BOOLEAN; 
r DOUBLE; 


r:= n$scanR(&pC, &status); 
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FIELD SCANNERS 
A a TL a 
Description 


The field scanners parse a fixed field in memory looking 
for a number. 


They are actually low level routines called by the string 
scanners. 


Numeric field format 
The numeric field may contain a leading 


e minus sign, and 
e in the case of hexadecimal, the characters "OX" or "Ox". 


The number must completely fill the field. No trailing 
spaces are allowed. 


Field scanning functions 


Use the following table to determine which field scanning 


function to use. 
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FIELD SCANNERS 


$scanD function 


$scanD converts a fixed field, decimal string number to its 
numerical equivalent. 


Function Syntax 


n$scanD ( 
pCh a CHAR, Address of the 
first character 
in the string. 


Size UNSIGNED, Width of the 
field size. 


pStatus a BOOLEAN {Address of a TRUE if a number 
boolean. was found. FALSE 
otherwise 


Decimal number 
scanned. 

Note: Undefined 
if number was 
not found. 


Example: 


function () := 

VAR on BYTE; 
field [40] CHAR; 
d LONG; 
Status BOOLEAN; 


n := nSread(nSWSIn, &field{0], SIZEOF field); 
;= SscanD(&field/0], n, &status); 


a 
‘i 
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FIELD SCANNERS 


$scanO function 


$scanO converts a fixed field, octal string number to its 
numerical equivalent. 


Address of the 
first character 
in the string. 


size UNSIGNED, Width of the 
field size. 


pStatus ~ BOOLEAN |Address of a TRUE if a number 
boolean. was found. FALSE 


otherwise 


Octal number 
scanned. 

Note: Undefined 
if number was 
not found. 


Example: 


function () := 
VAR n BYTE; 
field [40] CHAR; 
o LONG; 
status BOOLEAN; 


= nSread(nSWSIn, &field[0], SIZEOF field); 
Sscan0(&field[0], n, &status); 


or) 
tt 
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FIELD SCANNERS 


$scanH function 


$scanH converts a fixed field, hexadecimal string number 
to its numerical equivalent. 


nSscanH ( 
pCh a CHAR, Address of the 
first character 
in the string. 


size UNSIGNED, Width of the 
field size. 


pStatus ~ BOOLEAN |Address of a TRUE if a number 
boolean. was found. FALSE 
otherwise 


Hexadecimal 
number scanned. 
Note: Undefined 
if number was 
not found. 


Example: 


function () := 

VAR n BYTE; 
field [40] CHAR; 
h LONG; 
Status BOOLEAN ; 


a 
| 


= nSread(nSWSIn, &fieldi[01]1, SIZEOF field); 
SscanH(&field{0], n, &status); 


> 
tl 
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FIELD SCANNERS 


$scanR function 


$scanR converts a fixed field, real string number to its 
numerical equivalent. 


Function Syntax 


Address of the 
first character 
in the string. 


size UNSIGNED, Width of the 
field size. 


pStatus ~ BOOLEAN {Address of a TRUE if a number 
boolean. was found. FALSE 


otherwise 


) DOUBLE ; Floating point 
number scanned. 


Note: Undefined 
if number was 
not found. 


Example: 


function () := 

VAR n BYTE; 
field [40] CHAR; 
r DOUBLE; 
Status BOOLEAN; 


n := nSread(nSWSIn, &field[0], SIZEOF field); 
SscanR(&field[0], n, &status); 


i 
i 
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Chapter 6. 


MEMORY MANAGEMENT 
OVERVIEW 


Introduction 


NOSL has an internal memory manager for managing the 
buffers, internal control blocks, and data space used by the 
nosis. 


This chapter contains information about the memory 
manager and important considerations when using virtual 
files and overlays. 


Uses $BUDDY and $BUFFER CUFs 


NOSL does most of its memory management through the 
$BUDDY memory management CUF. The virtual file nosl, 
VirFil, is the only exception as it manages memory directly 
through the $$MEMGET and $$MEMREL UFRs. 


The $BUFFER CUF, which calls the $BUDDY CUF, is also 
used for memory management. 


Incompatibility with the memory management UFRs 


Because the memory management UFRs allocate all 
available logical memory when initialized, they are not 
compatible with NOSL. 


The $ALLOC and $BUDDY CUFs are compatible with NOSL 
and may be used instead. 
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VIRTUAL FILES 


Introduction 


The virtual file nosl, VirFil, will allocate as much memory 
as is needed to maintain the file in memory. 


Memory limited by the PCR 


The memory allocated by VirFil is limited by the maximum 
task memory limit set in the program communications 
region, PCR. 


Caution when using virtual files 


Because there is the potential for VirFil to allocate all of 
the available memory, you should insure that all of the 
streams you are going to use in a program are open before 
writing to a virtual file. Otherwise, NOSL may not have 
enough memory available to open the streams. 
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OVERLAYS 
RR NR RE a I I a I 
Introduction 


DASL programs with overlays may use NOSL but should be 
careful when overlaying code. 


Indirect calls through pointers 


All of the NOSL functions, except n$open, do indirect calls 
through pointers. This means that the functions that are 
called indirectly must be accessible whenever the nos! is 
accessed. 


Accessing a nos! in multiple overlays 


If you have a nos!| that is opened, and then overlayed with 
code that accesses the nosl, you must insure that the NOSL 
code is LINKed into an area of memory that is present 
during the execution of both overlays. 
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Chapter 7. 


ERROR HANDLING 
OVERVIEW 


6 NY NSS NTE 
Introduction 


NOSL contains internal error handling routines as well as a 
provision for customizing error handling. 


This chapter describes the NOSL error handler and contains 
instructions on how to customize error handling. 


When NOSL uses the error handler 


NOSL calls the error handler from any NOSL function that 
detects a fatal error when it is processing a stream. 


The default error handling routines 


If you do not customize error handling, and a fatal error 
occurs, the nos! functions will call the default error 
handling routines. 


The default error handling routines call $ERMSG on any 
error. 
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OVERVIEW 


Major reason to customize error handling 


The major reason for customizing error handling is to 
recover from errors that may not be considered fatal by 
your program. 


Example: n$open will generate a fatal error if an open is 
performed on a nonexistent file. Quite often, this is not 
considered a fatal error. 
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CUSTOMIZING ERROR HANDLING 
ee ae EE en eh ee ee ee 
Overview 


This section contains the information needed to customize 
error handling. 


Error codes 


NOSL updates the standard RMS error code, $ERRC, which may be 
used by your error routines. 


e $ERRC.$FUNC contains 
e the system code number for RMS system call errors, 
e the UFR class for UFR errors, and 
e the NOSL function code for NOSL errors. 

e $ERRC.$CODE contains the error number. 


Symbolic values for $ERRC.$FUNC may be found in 


D$ERRNUM/TEXT. Symbolic values for $ERRC.$CODE may 
be found in D$ ERRCODE/TEXT. 


State of a stream 
Determining whether an error is fatal or not should partly 
depend on the state of the stream after the error. A stream 
will be left in a defined state following a fatal error if 
e ang$open failed because of a nonexistent file, or 
e an illegal NOSL operation was attempted, such as a 


n$read on a Print nosl. 


Otherwise, the stream is left in an undefined state. 
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CUSTOMIZING ERROR HANDLING 


n$ErrorData type 


The n$ErrorData type is a type that must be defined by 
you. Variables of this type may be used to store 
information that will be passed into the error handling 
routines when a fatal error occurs. 


Example: This example uses n$ErrorData to store a pointer 
to the filename related to each stream. This filename can 


later be displayed by the error handling routines on a fatal 
error. 


Ty PDEF nSErrorData A SNAMEEXTENV ; 
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CUSTOMIZING ERROR HANDLING 


n$ErrorFunc type 


Use the n$ErrorFunc to declare functions that will be called 
by the NOSL functions when an error occurs. 


Note: Do not call any NOSL functions from the error 
function. 


n$ErrorFunc is defined as follows: 


TYPDEF nSErrorFunc ( 
eD a nSErrorData Address of data that you define. |] 
The address of the data passed to 


nSopen when a stream is opened 
will be passed as this parameter 
if an error occurs. 


Example: The following program segment defines an error 
function that will call $ERMSG on anything other than an 
open error. 


function nSErrorFunc := 


{ 


IF SERRC.SFUNC ~= SCSOPENENV 
& SERRC.SCODE = SUECOPN1 THEN SERMSG(); 


}; 
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CUSTOMIZING ERROR HANDLING 


Specifying error parameters to n$open 


The NOSL function n$open, may be passed the address of 
an error function and error data. Ifa fatal error occurs on 
that nosl during the nosl open or any other NOSL function, 
the error function will be called and the address of the 
error data will be passed as a parameter to the error 
function. 


Example: 


out nSStreamn; 


function () := 


out := nSopen(WSOut, &errorF, &errorD) ; 


Specifying error parameters to n$fKind 


The NOSL function n$fKind also accepts the address of an 
error function and error data as parameters. If a fatal 
error occurs during n$fKind, the error function will be 
called and the address of the error data will be passed as a 
parameter to the error function. 


Example: 


fFileSpk SFILESPK := { 
{ 'IN os ' Pe ! a J ' }, 
SF ILNAMR, SNOADR, &'TEXT' ,&' ; 
}; 


function () := 
VAR dK BYTE; 
{ 
IF SSCANFLS(&fileSpk, 1) && DSCFLAG THEN SERMSGC(C); 
dK := nS$fKind(&fileSpk.SFSOSFT,, S&errorF, &errorD); — 
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